/*
 * Copyright (C) 2004 Nokia Oyj, all rights reserved.
 * You can be shot just for looking at this file.
 */
package com.kaixin001.tk.api;


/**
 * Interface for scheduler service
 * @author Dmitry Mikhailov
 */
public interface Scheduler
{

    /**
     * Schedules periodical execution of given task.
     * Task is always executed at equal periods starting from the base time.
     * @param task task to execute
     * @param base base time (milliseconds since Unix epoch).
     * If <code>base</code> is in the future, task will be first run at
     * this time. If <code>base</code> is in the past,
     * the task will be first run at the time for next periodic execution.
     * @param period period between executions (milliseconds)
     * @param skipConcurrent what to do when the time for next execution
     * has come while the previos is still in progress.
     * If <code>true</code>, then current execution will be skipped.
     * If <code>false</code>, then current execution will be executed
 * immediately after previous execution finishes.
     * @return ID for the scheduled task, can be used in subsequent calls
     * @see #rescheduleTask(Object, long, long)
 * @see #cancelTask(Object)
     */
    Object scheduleTask(Runnable task, long base, long period,
        boolean skipConcurrent);

    /**
 * Re-schedules the task that is already scheduled.
     * @param id task ID as returned from <code>scheduleTask()</code>
     * @param base see <code>scheduleTask()</code>
     * @param period see <code>scheduleTask()</code>
     * @return the same task ID
     * @throws IllegalArgumentException if ID of the task is unknown
 * @see #scheduleTask(Runnable, long, long, boolean)
     */
    Object rescheduleTask(Object id, long base, long period)
        throws IllegalArgumentException;

    /**
     * Cancels execution of the scheduled task with given ID
     * @param id ID of the task
     * @see #scheduleTask(Runnable, long, long, boolean)
     */
    void cancelTask(Object id);

}
